FMOD API User Manual 2.02

5. White Papers | Handle System

Handle System

Introduction

The FMOD Studio and Core API returns pointers to types. Some of these types are actually implemented as an underlying handle with the handle data represented to the user as a pointer type. This section explains the underlying representation and lifetime of these objects.

General Information

All FMOD types, whether they are represented internally via pointer or handle, look like a pointer type. No matter the type, a null pointer will never be returned as a valid result, but it is not safe to assume anything else about the pointer value. The user should not assume that the pointer value falls in any particular address range, or that it has any zero bits in the bottom of the pointer value address.

All FMOD types are equivalent for both the C and C++ API. It is possible to cast between the appropriate types by re-interpreting the pointer type directly.

Core API Channels

FMOD Channels are returned to the user as a pointer but actually consist of 32bits of packed integer handle data. This allows channels to be re-used safely.

If a Channel is stopped with ChannelControl::stop or ends naturally, the Channel handle will become invalid and return FMOD_ERR_INVALID_HANDLE.

If not enough channels are specified at System::init and an existing virtual channel is stolen by the FMOD priority system, then the handle to the stolen channel becomes 'invalid'. Subsequent Channel commands to a stolen handle will return FMOD_ERR_CHANNEL_STOLEN.

Core API Channel Groups

FMOD Channel Groups are returned to the user directly as a pointer. Once the user destroys a channel group, it is not safe to call FMOD functions with that pointer.

Core API System

FMOD system object is returned to the user directly as a pointer. Once the user destroys the core system, is is not safe to call FMOD functions with that pointer.

Studio API Types

FMOD Studio types are returned to the user as a pointer but actually consist of packed handle data. If the underlying type has been destroyed then the API will return FMOD_ERR_INVALID_HANDLE. An example of this would be unloading a Studio::Bank and then referencing a Studio::EventDescription belonging to that bank.